Update Receiving Event
Method: PUT
/events/receiving/{id}
As a Customer of iFoodDS, you use the iFoodDS Receive Event API to update FSMA 204 receive event data in the iFoodDS Trace Exchange platform.
Event records will be stored for a minimum of two years.
info
This endpoint is being refined and thus subject to change. These docs will update when changes are made.
Request
Type: application/json
The {id} of the path is the event ID retrieved from:
- Completion of a succesful POST. Example:
"request_ids": ["9ed5911f-f6a4-4ba2-9eb4-d6428237be28"] - Within the payload results of a GET. Example:
"id": "7b5c43c3-3526-4135-a602-0e3979c21d88"
The body of the request comprises three main sections: the productMasterDataList, the locationMasterList, and the eventList. The first two sections are there to reduce the duplication of data you need to provide for the eventList.
{
"payloadId": "<payload id>",
"transmissionDateTime": "<transmission date time>",
"productMasterDataList": [
{
"itemCode": "<item code>",
"itemDescription": "<item description>",
"businessUnit": "<business unit>",
"alternateItemCode": "<alternate item code>",
"gtin": "<GTIN>",
"itemUpc": "<item UPC>",
"innerPackUpc": "<inner pack UPC>",
"plu": "<PLU>",
"isFtlItem": true,
"ftlCategory": "<FTL category>",
"brandName": "<brand name>",
"packStyle": "<pack style>",
"packSize": "<pack size>",
"productCommodity": "<product commodity>",
"productVariety": "<product variety>",
"scientificName": "<scientific name>",
"acceptableSpeciesName": "<acceptable species name>",
"isCoveredByGdst": true
}
],
"locationMasterList": [
{
"locationName": "<location name>",
"locationCode": "<location code>",
"businessUnit": "<business unit>",
"market": "<market>",
"region": "<region>",
"locationType": "<location type>",
"parentLocationId": "<parent location id>",
"gln": "<GLN>",
"glnAssignedBy": "<GLN assigned by>",
"duns": "<DUNS number>",
"alternateLocationCode": "<alternate location code>",
"phoneNumber": "<phone number>",
"isPrimaryLocation": true,
"isCoveredByGdst": false,
"address": {
"streetAddress1": "<street address 1>",
"streetAddress2": "<street address 2>",
"city": "<city>",
"state": "<state>",
"postalCode": "<postal code>",
"country": "<country>"
},
"geoLocation": {
"gpsCoordinates": [
"<latitude>",
"<longitude>"
],
"geoFence": [
[
"<latitude1>",
"<longitude1>"
],
[
"<latitude2>",
"<longitude2>"
]
]
}
}
],
"eventList": [
{
"eventId": "<event id>",
"purchaseOrderDate": "<purchase order date>",
"purchaseOrderNumber": "<purchase order number>",
"businessUnit": "<business unit>",
"eventTransactionTime": "<event transaction time>",
"billOfLadingNumber": "<Bill of Lading number>",
"asnNumber": "<ASN number>",
"eventDateTime": "<event date time>",
"expectedDeliveryDate": "<expected delivery date>",
"shipFromLocationCode": "<ship from location code>",
"shipToLocationCode": "<ship to location code>",
"standardCarrierAlphaCode": "<SCAC>",
"carrierShipmentMethod": "<shipment method>",
"equipmentDescription": "<equipment description>",
"equipmentNumber": "<equipment number>",
"appointmentNumber": "<appointment number>",
"carrierTrackingNumber": "<carrier tracking number>",
"loadPlanningNumber": "<load planning number>",
"methodOfPayment": "<method of payment>",
"shipmentLadingQuantity": "<lading quantity>",
"shipmentLadingUom": "<lading UOM>",
"productList": [
{
"productId": "<product id>",
"palletId": "<pallet id>",
"palletLpn": "<pallet LPN>",
"palletPackagingDescriptionCode": "<pallet packaging description>",
"palletHigh": "<pallet high>",
"palletTie": "<pallet tie>",
"iotDevice": "<IoT device>",
"poLineNumber": "<PO line number>",
"vendorItemCode": "<vendor item code>",
"vendorItemDescription": "<vendor item description>",
"purchaserItemCode": "<purchaser item code>",
"caseGtin": "<case GTIN>",
"caseLotNumber": "<case lot number>",
"lotNumber": "<lot number>",
"gtin14": "<GTIN-14>",
"gtin12": "<GTIN-12>",
"expirationDate": "<expiration date>",
"productionDate": "<production date>",
"packagingDate": "<packaging date>",
"bestBeforeDate": "<best before date>",
"harvestDate": "<harvest date>",
"countryOfOrigin": "<country of origin>",
"shipQuantity": "<ship quantity>",
"shipQuantityUom": "<ship quantity UOM>",
"itemUpc": "<item UPC>",
"itemPlu": "<item PLU>",
"itemDateCode": "<item date code>",
"itemDateCodeType": "<item date code type>",
"tlcSourceReferenceDuns": "<DUNS>",
"tlcSourceReferenceGln": "<GLN>",
"tlcSourceReferenceFfrn": "<FFRN>",
"tlcSourceReferenceFei": "<FEI>",
"tlcSourceReferenceUrl": "<URL>",
"tlcSourceReferenceOther": "<OTHER>",
"tlcSourceName": "<TLC source name>",
"tlcSourceAddress1": "<address 1>",
"tlcSourceAddress2": "<address 2>",
"tlcSourceCity": "<city>",
"tlcSourceState": "<state>",
"tlcSourcePostalCode": "<postal code>",
"tlcSourceCountry": "<country>",
"tlcSourcePhoneNumber": "<phone number>"
}
]
}
]
}
tip
While the example payload above includes only one location object in the locationMasterList, your real payload will minimally contain two: the ship from location and the ship to location.
Data Constraints
Please note the following data constraints:
stringsallow a maximum of 100 charactersdatesmust use the format:yyyy-MM-dddatetimesmust use the format:yyyy-MM-ddTHH:mm:ssZ(UTC) oryyyy-MM-ddTHH:mm:ss-hh:00(UTC minus) oryyyy-MM-ddTHH:mm:ss+hh:00(UTC plus)
Payload Data
Optional
payloadId(string): A unique payload id supplied by the party submitting the event.transmissionDateTime(datetime): The date and time the payload was sent.
Product Data
Required
itemCode(string): The vendor or purchaser item code that will be referenced in the eventitemDescription(string): Product Description from the product owner or original purchase order
Additional information will be required in the eventList section.
Optional
alternateItemCode(string): This field provides sender and shipper to use and alternate identifier for products. This could be a URL, a UUID, or other globally unique identification scheme. The important thing is that it is unique per product and shared between shipper and receiver. For example, this could be a GS1 Digital Link URL for the productgtin(string): Case-level Global Trade Identification Number (GTIN-14). GS1 GTIN Executive SummaryitemUpc(string): Item-level Universal Product Code, may be GTIN-8, GTIN-12, or GTIN-13. GS1 GTIN Executive SummaryinnerPackUpc(string): Point of sale barcode, may be GTIN-8, GTIN-12, GTIN-13, or GTIN-14. GS1 GTIN Executive Summaryplu(string): Item-level Price Look-up Code. PLU Codes Search — IFPSisFtlItem(boolean): Indicates whether product is on the Food Traceability List (FTL)ftlCategory(string)*: Indicates the product's FTL category, i.e. “soft cheese”, “shell eggs”, “nut butter”, “cucumbers”, “herbs”, “leafy greens”, “melons”, “peppers”, “sprouts”, “tomatoes”, “tropical tree fruits”, “fresh-cut fruits”, “fresh-cut vegetables”, “finfish”, “smoked finfish”, “crustaceans”, “molluscan shellfish”, “ready-to-eat deli salads”, or “multiple-ftl-ingredients” *Required if on the FTLbrandName(string): The brand of the product that appears on the consumer packagepackStyle(string): Product's pack style, e.g. "Case", "Carton", "Tray", "Clamshell", etc.packSize(string): Product's pack size as Packaging Configuration OR Count OR Weight + Unit of Measure, e.g. "20 x 12 oz bags"productCommodity(string): For fresh produce, a description of the commodity, e.g. "Peppers"productVariety(string): For fresh produce a description of the variety when applicable, e.g. "Jalapeno"scientificName(string): For seafood the scientific name of the species, see: FDA Seafood ListacceptableSpeciesName(string): For seafood a description of the common species name, see: FDA Seafood ListisCoveredByGdst(boolean): Flag to indicate that product is part of GDST
Location Data
Required
locationName(string): Name of vendor's or purchaser's location referenced in the eventlocationCode(string): Vendor's or purchaser's location code referenced in the event
If address and contact information is already set up in master data with locationCode, then the address information is not required. Otherwise, it is required. Provide at least one of the following:
gln(string): GS1 Global Location Number, a 13-digit string. GS1 GTIN Executive Summaryduns(string): Dun & Bradstreet Data Universal Numbering System number, a 9-digit stringaddress(object):streetAddress1(string): Physical street address line 1 informationstreetAddress2(string): Physical street address line 2 information, if applicablecity(string): City locationstate(string): State or region locationpostalCode(string): ZIP or postal codecountry(string): Country locationgeoLocationoptional (object): Consisting of either...gpsCoordinatesas anarray of stringsrepresenting the latitude followed by longitude expressed in degrees and minutes ORgeoFenceas anarray of string arraysrepresenting the latitude followed by longitude expressed in degrees and minutes for each set of coordinates defining the geo fence
Optional
businessUnit(string): Indicates the business unit associated with the location.market(string): Indicates the market associated with the location.region(string): Indicates the region associated with the location.locationType(string): Indicates whether the location is "Internal", "Supplier", or "Customer"parentLocationId(string): To create a hierarchy of locations (divisions, regions, etc.), use this field to point to the location’s parent locationglnAssignedBy(string): Indicates whether it was assigned by "GS1", "GLOBALGAP", "Internal", "Trading Partner", or "Other"alternateLocationCode(string): This field provides sender and shipper to use and alternate identifier for connecting locations. This could be a URL, a UUID, or other globally unique identification scheme. The important thing is that it is unique per location and is shared between shipper and receiver. For example, this could be a GS1 Digital Link or Google Place IDphoneNumber(string)*: Phone number including country code with format: +1.999.999.999 *This field is required ifaddressis used to identify locationisPrimaryLocation(boolean): This indicates that the location is the primary headquarter location for the organizationisCoveredByGdst(boolean): Indicates that this location is covered by the Global Dialogue on Seafood Traceability requirements
Event Data
warning
When sending an event payload, the payload must contain the complete set of records for the corresponding event date time. DO NOT send more than one payload with the same event date time.
Required
purchaseOrderNumber(string): The purchase order number you received from your customereventDateTime(datetime): Date and time the order was actually receivedshipFromLocationCode(string): References a location fromlocationMasterList. The vendor’s location code for ship from locationshipToLocationCode(string): References a location fromlocationMasterList. The buyer’s location code for ship to location. This should be provided as part of the Purchase OrderproductList(array): List of items received in the event
Optional
eventId(string): unique id to identify the event.purchaseOrderDate(date): Purchase order datebusinessUnit(string): Indicates the business unit associated with the event.eventTransactionTime(datetime): The date and time of the event occured.billOfLadingNumber(string): The Bill of Lading provided by you to your customerasnNumber(string): This is the unique identifier for the ASN you provide to your customer (if you provide one)expectedDeliveryDate(date): Date when shipper expects to deliver goods to recipientstandardCarrierAlphaCode(string): Four‑letter code uniquely identifying the transportation carrier.carrierShipmentMethod(string): Mode of transport used for the shipment.equipmentDescription(string): Type of transportation equipment used for the load.equipmentNumber(string): Unique identifier of the trailer, container, or equipmentappointmentNumber(string): Scheduled delivery appointment identifier from receiver or carriercarrierTrackingNumber(string): Carrier‑assigned tracking number for shipment visibility.loadPlanningNumber(string): Identifier linking shipment to a transportation management loadmethodOfPayment(string): Indicates who pays the freight charges.shipmentLadingQuantity(number): Total quantity of goods loaded for shipment.shipmentLadingUom(string): Unit of measure for the lading quantity.
Products
Required
vendorItemCode(string): This is the vendor's (or your) internal product id or item code stored in their master data. If the cases received are labeled with a case GTIN-14, this information should be stored in the product master data record for the item code / product id referencedshipQuantity(number): The number of units of this Traceability Lot Code on the palletshipQuantityUom(string): Unit of measure (e.g., Case)
Traceability Lot Code (TLC) Source could be either the address and phone of the facility that produced the TLC, or a reference to a database that provides the address and phone for the TLC Source. Provide at least one of the following as a reference:
tlcSourceReferenceDuns(string): 9 Digit Dun & Bradstreet Number, must be registered in DUNS and available to FDA. The TLC Source reference DUNS + 4tlcSourceReferenceGln(string): 13 Digit GS1 Global Location Number. Must be registered in GS1 US Data Hub | Location. The TLC Source reference GLNtlcSourceReferenceFfrn(string): FDA Food Facility Registration Number, must be current in FDA Facility Registration Database. The TLC Source reference FFRNtlcSourceReferenceFei(string): FDA Establishment Identifier. This number may be requested at no cost from FDA. The TLC Source reference FEItlcSourceReferenceUrl(string): A web link point to a site where FDA may access the TLC Source Reference. The TLC Source reference URLtlcSourceReferenceOther(string): This could be another identifier. One can prefix the ID with a type to make it easier to lookup. For example: 'USDAEgg: Plant 42"
If a TLC Source Reference is not provided, you must include all of the following information:
tlcSourceName(string): The TLC source nametlcSourceAddress1(string): The TLC Source physical street address line 1 informationtlcSourceAddress2(string): The TLC Source physical street address line 2 information, if applicabletlcSourceCity(string): The TLC Source city locationtlcSourceState(string): The TLC Source state or region locationtlcSourcePostalCode(string): The TLC Source ZIP or postal codetlcSourceCountry(string): The TLC Source countrytlcSourcePhoneNumber(string): The TLC Source phone number
Optional
businessUnit(string): Indicates the business unit associated with the product.palletId(string): GS1 Serial Shipping Container Code, SSCC-18 (if provided)palletLpn(string): Internally generated License Plate Number (e.g., from Warehouse Management System)palletHigh(number): Number of layers stacked vertically on the pallet.palletTie(number): Number of cases per layer on a pallet.iotDevice(string): If you provide an IoT device attached to the pallet, capture its identifier herepoLineNumber(string): Line number in the purchase order for this item; this links the Traceability Lot Code to the line item on the POproductId(string): A unique productId to help identify potential post/put issuespurchaserItemCode(string): This is the purchaser's product item code provided via their PO or other form of data sharing. This information is stored in your master data. If the customer has shared a GTIN, it should be stored in the master data record. The purchaser's item code may also be the purchaser’s GTIN, but not necessarily-–it could be a SKU or another type of ID. This may point to the receiver’s master product data recordcaseGtin(string): GTIN-14 of cases on palletcaseLotNumber(string): This is the Lot Number displayed on the case label you are providing to the customer. This will be required starting in January 2026expirationDate(date): The expiration dateproductionDate(date): The production datepackagingDate(date): The packaging datebestBeforeDate(date): The best before dateharvestDate(date): The harvesting datecountryOfOrigin(string): The three letter country code of originitemUpc(string): Item-level Universal Product Code, may be GTIN-8, GTIN-12, or GTIN-13. GS1 GTIN Executive SummaryitemPlu(string): Include if items in the case are marked with PLU numbers; this may be used instead of UPCitemDateCode(date): Often items are marked with a date code; if so, this field can be used to capture ititemDateCodeType(string): Indicate the type of date code if provided
Sample Payload
{
"payloadId": "SHIP-PL-0001",
"transmissionDateTime": "2026-01-21T16:15:00Z",
"productMasterDataList": [
{
"itemCode": "APL123",
"businessUnit": "Produce-West",
"itemDescription": "Fresh Red Apples",
"isFtlItem": false,
"ftlCategory": "Tree Fruit",
"brandName": "OrchardBest",
"packStyle": "Bag",
"packSize": "5 lb",
"productCommodity": "Apples",
"productVariety": "Red Delicious",
"scientificName": "Malus domestica",
"acceptableSpeciesName": "Apple",
"gtin": "00012345000012",
"innerPackUpc": "012345678905",
"itemUpc": "012345678912",
"plu": "4015",
"alternateItemCode": "APL-RED-5LB",
"isCoveredByGdst": true
},
{
"itemCode": "BNN456",
"businessUnit": "Produce-West",
"itemDescription": "Organic Bananas",
"isFtlItem": false,
"ftlCategory": "Tropical Fruit",
"brandName": "TropiGold",
"packStyle": "Bunch",
"packSize": "2 lb",
"productCommodity": "Bananas",
"productVariety": "Cavendish",
"scientificName": "Musa acuminata",
"acceptableSpeciesName": "Banana",
"gtin": "00098765000045",
"innerPackUpc": "098765432109",
"itemUpc": "098765432118",
"plu": "94011",
"alternateItemCode": "BNN-ORG-2LB",
"isCoveredByGdst": false
}
],
"locationMasterList": [
{
"locationCode": "LOC100",
"locationName": "Central Distribution Center",
"businessUnit": "West",
"region": "California",
"market": "Bay Area",
"locationType": "Warehouse",
"phoneNumber": "+1-555-123-4567",
"address": {
"streetAddress1": "100 Market Way",
"streetAddress2": "Suite 200",
"city": "San Jose",
"state": "CA",
"postalCode": "95110",
"country": "USA"
},
"geoLocation": {
"gpsCoordinates": ["37.3382", "-121.8863"],
"geoFence": [
["37.3380", "-121.8860"],
["37.3384", "-121.8866"]
]
},
"gln": "1234567890001",
"glnAssignedBy": "GS1",
"duns": "123456789",
"alternateLocationCode": "CDC-01",
"parentLocationId": "PARENT-LOC-01",
"isCoveredByGdst": true,
"isPrimaryLocation": true
},
{
"locationCode": "LOC200",
"locationName": "North Retail Store",
"locationType": "Store",
"phoneNumber": "+1-555-987-6543",
"gln": "1234567890002",
"glnAssignedBy": "GS1",
"duns": "987654321",
"alternateLocationCode": "NRS-01",
"parentLocationId": "PARENT-LOC-02",
"isCoveredByGdst": false,
"isPrimaryLocation": false,
"address": {
"streetAddress1": "500 Retail Plaza",
"streetAddress2": "",
"city": "San Francisco",
"state": "CA",
"postalCode": "94103",
"country": "USA"
},
"geoLocation": {
"gpsCoordinates": ["37.7749", "-122.4194"],
"geoFence": [
["37.7747", "-122.4190"],
["37.7751", "-122.4198"]
]
}
}
],
"eventList": [
{
"eventId": "SHIP-1001",
"purchaseOrderDate": "2026-01-20",
"purchaseOrderNumber": "PO-555123",
"businessUnit": "Produce-West",
"eventTransactionTime": "2026-01-21T15:40:00Z",
"billOfLadingNumber": "BOL-778899",
"asnNumber": "ASN-445566",
"eventDateTime": "2026-01-21T15:45:00Z",
"expectedDeliveryDate": "2026-01-22",
"shipFromLocationCode": "LOC100",
"shipToLocationCode": "LOC200",
"standardCarrierAlphaCode": "SCAC123",
"carrierShipmentMethod": "Truckload",
"equipmentDescription": "Reefer Trailer",
"equipmentNumber": "TRLR-5566",
"appointmentNumber": "APPT-20260121-01",
"carrierTrackingNumber": "TRACK-998877",
"loadPlanningNumber": "LOAD-PLN-12345",
"methodOfPayment": "Prepaid",
"shipmentLadingQuantity": 1200,
"shipmentLadingUom": "LB",
"productList": [
{
"productId": "APL-PROD-001",
"palletId": "PALLET-APL-001",
"palletLpn": "LPN-APL-001",
"iotDevice": "IOT-APL-TRACKER-01",
"poLineNumber": "10",
"vendorItemCode": "APL123",
"vendorItemDescription": "Fresh Red Apples",
"purchaserItemCode": "APL-PO-ITEM-01",
"caseGtin": "00012345000012",
"caseLotNumber": "LOT-APL-20260115",
"expirationDate": "2026-02-10",
"productionDate": "2026-01-15",
"packagingDate": "2026-01-16",
"bestBeforeDate": "2026-02-05",
"harvestDate": "2026-01-10",
"countryOfOrigin": "USA",
"shipQuantity": 500,
"shipQuantityUom": "LB",
"itemUpc": "012345678912",
"itemPlu": "4015",
"itemDateCode": "20260210",
"itemDateCodeType": "expiration",
"tlcSourceName": "OrchardBest Packing House",
"tlcSourceReferenceGln": "1234567890001",
"tlcSourceReferenceDuns": "123456789",
"tlcSourceReferenceFfrn": "FFRN-APL-001",
"tlcSourceReferenceFei": "FEI-APL-001",
"tlcSourceReferenceUrl": "https://example.com/tlc/apl123",
"tlcSourceReferenceOther": "USDAPlant42",
"tlcSourceAddress1": "12 Orchard Lane",
"tlcSourceAddress2": "",
"tlcSourceCity": "Fresno",
"tlcSourceState": "CA",
"tlcSourcePostalCode": "93722",
"tlcSourceCountry": "USA",
"tlcSourcePhoneNumber": "+1-559-555-1212",
"palletPackagingDescriptionCode": "BAG",
"palletHigh": 4,
"palletTie": 12,
"lotNumber": "LOT-APL-20260115",
"gtin14": "10001234500001",
"gtin12": "012345678912"
},
{
"productId": "BNN-PROD-001",
"palletId": "PALLET-BNN-001",
"palletLpn": "LPN-BNN-001",
"iotDevice": "IOT-BNN-TRACKER-01",
"poLineNumber": "20",
"vendorItemCode": "BNN456",
"vendorItemDescription": "Organic Bananas",
"purchaserItemCode": "BNN-PO-ITEM-01",
"caseGtin": "00098765000045",
"caseLotNumber": "LOT-BNN-20260114",
"expirationDate": "2026-02-08",
"productionDate": "2026-01-14",
"packagingDate": "2026-01-15",
"bestBeforeDate": "2026-02-03",
"harvestDate": "2026-01-12",
"countryOfOrigin": "ECU",
"shipQuantity": 700,
"shipQuantityUom": "LB",
"itemUpc": "098765432118",
"itemPlu": "94011",
"itemDateCode": "20260208",
"itemDateCodeType": "expiration",
"tlcSourceName": "TropiGold Cooperative",
"tlcSourceReferenceGln": "1234567890002",
"tlcSourceReferenceDuns": "987654321",
"tlcSourceReferenceFfrn": "FFRN-BNN-001",
"tlcSourceReferenceFei": "FEI-BNN-001",
"tlcSourceReferenceUrl": "https://example.com/tlc/bnn456",
"tlcSourceReferenceOther": "USDAPlant99",
"tlcSourceAddress1": "45 Banana Road",
"tlcSourceAddress2": "",
"tlcSourceCity": "Guayaquil",
"tlcSourceState": "GYE",
"tlcSourcePostalCode": "090150",
"tlcSourceCountry": "ECU",
"tlcSourcePhoneNumber": "+593-4-555-1212",
"palletPackagingDescriptionCode": "BUNCH",
"palletHigh": 5,
"palletTie": 10,
"lotNumber": "LOT-BNN-20260114",
"gtin14": "10009876500004",
"gtin12": "098765432118"
}
]
}
]
}
Response
- 200
- 400
Receiving event data ingested successfully
{
"request_ids": [
"1abc2f7e-6ca2-40ec-9566-19a850945d7f"
]
}
Description of what user-fixable validation error occurred and in what part of the payload
{
"detail": [
{
"type": "missing",
"loc": [
"body",
"eventList",
"purchaseOrderNumber"
],
"msg": "Field required",
}
]
}